home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / pascal / ovrlay.txt < prev    next >
Encoding:
Text File  |  1990-01-27  |  9.8 KB  |  216 lines
  1. This file explains some of the low-level details of the overlay manager.
  2. It is assumed that the reader is familiar with the documentation provided
  3. in the Turbo Pascal manuals relating to overlays, and with the use of
  4. overlays in general.
  5.  
  6.  
  7. Overview
  8.  
  9. Each overlaid unit has three parts: a static "dispatcher" segment, the
  10. actual overlaid code, and a transient fixup table.  The static dispatcher
  11. for each unit is a small code segment that always remains in memory.  It
  12. transfers control to the overlay manager if the unit is not currently in
  13. memory, or directly to the unit in the overlay buffer if it is already
  14. present.  The overlaid code itself is stored in the application's OVR
  15. file, which is read by the overlay manager each time it must reload an
  16. overlay.  The fixup table is also stored in the OVR file, and is used to
  17. correct intersegment references in the overlay code, based on the starting
  18. address of the program.
  19.  
  20.  
  21. The Static Dispatcher
  22.  
  23. Each static dispatcher is a small code segment that's linked into the EXE
  24. file.  A unique dispatcher always remains in memory for each overlaid
  25. unit.  Whenever you call a procedure in an overlaid unit, you're really
  26. calling a tiny (5 byte) routine in the static dispatcher.
  27.  
  28. If you have the Turbo Pascal run-time library source, you can find the
  29. "official" documentation for this structure in SE.ASM, which is in INCLUDE.ARC.
  30.  
  31. Each dispatcher begins with a 32 byte header area, which is laid out as
  32. follows:
  33.  
  34. type
  35.   OverlayHeader = record
  36.     {00} ReturnInt : Word;
  37.     {02} ReturnOfs : Word;
  38.     {04} FileOfs : LongInt;
  39.     {08} CodeSize : Word;
  40.     {0A} FixupSize : Word;
  41.     {0C} EntryPts : Word;
  42.     {0E} CodeListNext : Word;
  43.     {10} LoadSegment : Word;
  44.     {12} Reprieved : Word;
  45.     {14} LoadListNext : Word;
  46.     {16} EmsPage : Word;
  47.     {18} EmsOffset : Word;
  48.     {1A} UserData : array [0..2] of Word;
  49.   end;
  50.  
  51. ReturnInt and ReturnOfs are used when RETurning to a unit that has been
  52. booted out by another unit.  ReturnInt always contains an INT $3F
  53. instruction.  ReturnOfs is a variable field.  These are explained in
  54. more detail later.
  55.  
  56. FileOfs is the offset of the overlaid code segment within the overlay file.
  57. The lowest value this can have is 4 because each overlay file starts with a
  58. four byte signature.
  59.  
  60. CodeSize specifies the number of bytes of actual code for this unit.  To
  61. determine the number of bytes required in the overlay buffer to load the
  62. code of the unit this must be rounded up to the next paragraph.
  63.  
  64. FixupSize denotes the transient space required while loading the overlay
  65. unit.  This must also be rounded up to the next paragraph.
  66.  
  67. EntryPts specifies the number of 5-byte jump vector entries in the static
  68. dispatcher.  Although you might think that this would be the same as the number
  69. of interfaced procedures and functions in the unit, that's not true.  The
  70. static dispatcher has an entry for _every_ procedure and function in the
  71. unit, whether it's global or local, interfaced or hidden.  The reason
  72. becomes clear when you think about passing procedure parameters -- even a
  73. non-interfaced routine can be called indirectly from outside of the unit,
  74. and the overlay manager must still be informed when to load the code in
  75. such a case.  This number thus provides a count of all the routines in a
  76. unit.  (It also adds one for the initialization block, if any.)
  77.  
  78. CodeListNext contains the static segment address of the next unit in a linked
  79. list of all overlaid units in the program.  The System unit variable
  80. OvrCodeList contains the segment of the first unit in the list.  A value of
  81. zero in CodeListNext marks the end of the list.  Segment addresses are
  82. relative to PrefixSeg+$10.
  83.  
  84. LoadSegment is initially zero.  When the overlay manager loads the unit
  85. from disk it stores the segment address where the unit was loaded here.
  86. If the overlay manager unloads the unit from memory, it sets LoadSegment
  87. back to zero.
  88.  
  89. Reprieved is a flag that is set to 1 when a unit that was on probation is
  90. reprieved.
  91.  
  92. LoadListNext contains the static segment address of the next unit in a linked
  93. list of all units that are currently loaded in the overlay buffer.  The
  94. System unit variable OvrLoadList contains the segment of the first unit in
  95. the list.  A value of zero in LoadListNext marks the end of the list.
  96. Segment addresses are absolute.
  97.  
  98. EmsPage contains the EMS physical-page number where the unit begins when the
  99. overlay file is stored in EMS memory.
  100.  
  101. EmsOffset contains the byte offset from the beginning of the EMS page when the
  102. overlay file is stored in EMS memory.
  103.  
  104. UserData is not used by the overlay system as far as anyone has been able to
  105. determine.
  106.  
  107.  
  108. The header is followed by a 5-byte "vector" for each procedure and function in
  109. the unit.  If the overlay isn't currently loaded, or is on probation, the
  110. vector consist of an INT $3F instruction, followed by one word of data that
  111. specifies the code offset of the routine being called, and an unused
  112. zero-byte.  This is the state of the dispatcher when the program is initially
  113. loaded.  The INT $3F serves to transfer control to the overlay manager's
  114. code.
  115.  
  116. If the overlay is already loaded into memory, and is not on probation, the
  117. vector is just a FAR JMP instruction that immediately transfers control to
  118. the real code in the overlay buffer.  Returning from an overlaid unit is done
  119. with a simple RETF instruction, just like with normal, non-overlaid routines,
  120. as the FAR JMP does not affect the return address on stack pushed by the
  121. original CALL.
  122.  
  123.  
  124. The Overlay File
  125.  
  126. The overlaid code itself is stored in the application's OVR file, which is
  127. read by the overlay manager each time it must reload an overlay.  If EMS
  128. overlays are activated, the OVR file is read entirely into EMS during
  129. initialization, and thereafter overlays are transferred to the overlay
  130. buffer from EMS rather than from disk.
  131.  
  132. The transient fixup tables are also stored in the OVR file, immediately
  133. following the code for each unit.  The overlay manager reads this
  134. information into the overlay buffer each time an overlay is loaded.  Fixup
  135. information is used to correct intersegment references in the overlay
  136. code, based on the starting address of the program.  This information is
  137. "transient" because it's used only when the overlay is being loaded; it
  138. doesn't retain space in the overlay buffer thereafter.
  139.  
  140.  
  141. Loading an Overlay
  142.  
  143. When a call is made to a function or procedure in an overlay that is not
  144. present in memory, the INT $3F instruction in the dispatcher transfers
  145. control to the overlay manager, which does the following:
  146.  
  147. 1.  Finds space for the overlay (perhaps by booting out other overlays).
  148.  
  149. 2.  Loads the required overlay code into memory and updates LoadSegment in the
  150. header.
  151.  
  152. 3.  Changes the INT $3F instructions in the dispatcher to FAR JMPs.  The
  153. code offset word following the INT $3F is used here to create the jump
  154. instruction.
  155.  
  156. 4.  Adjusts the return address of the INT instruction.  If left alone, this
  157. would return to the third byte of the FAR JMP instruction.  It's adjusted
  158. to return to the beginning of the FAR JMP.
  159.  
  160. 5.  Returns to the dispatcher.  This tranfers control to the FAR JMP code,
  161. which in turn jumps to the requested procedure.
  162.  
  163.  
  164. Removing an Overlay
  165.  
  166. Special precautions are taken when an overlaid unit is to be removed from
  167. the overlay buffer.  Without this preparation, when you are about to
  168. return to an overlaid unit that is no longer in the overlay buffer, maybe
  169. because you call one overlay from another, the return address on the stack
  170. would point to the physical address where the CALL instruction USED TO BE.
  171. This clearly won't work.  Something must be done to avoid this situation,
  172. and that's where ReturnInt and ReturnOfs enter the picture.
  173.  
  174. When a unit is to be moved or removed from the overlay buffer, the overlay
  175. manager traverses the stack, looking for return addresses that point into
  176. that unit.  Since a unit is not likely to be reloaded at the same address it
  177. came from, all return addresses into the unit must be changed.  It does this
  178. by jumping through the BP links on the stack until it meets the zero pushed
  179. by the Turbo RTL startup code.  This is the reason all global routines in an
  180. overlaid unit must be FAR and must set up a stack frame.  In each return
  181. address on the stack, the segment value is changed to point to the static
  182. dispatcher segment.  That way they can be recognized when they are to be
  183. changed again during the reload process.  The most-recently-pushed return
  184. address needs special handling, since it the first one that will be accessed
  185. and will cause the unit to be reloaded.  Its offset is copied into ReturnOfs
  186. to be used later, and the offset part on the stack is set to zero so that it
  187. points to ReturnInt, which contains an INT $3F instruction.  This sets the
  188. stage for a safe landing when it's time to make the return trip.
  189.  
  190.  
  191. Reloading the Overlay
  192.  
  193. When the program reaches the RETF instruction that wants to return to the
  194. unit that was unloaded, control passes to the INT $3F instruction at offset
  195. zero of the dispatcher.  This transfers control to the overlay manager,
  196. which reloads the unit, and then traverses the stack once more, finding the
  197. return addresses having segment values pointing to the static dispatcher
  198. segment, and changing them to the actual physical segment in the overlay
  199. buffer.  There's no need to change the offset parts; an overlay is always
  200. loaded at a paragraph boundary, so the offsets don't change.  The overlay
  201. manager then uses the value from ReturnOfs to create a return address to the
  202. appropriate point in the code.
  203.  
  204.  
  205.  
  206. If you have any additions or corrections for this file, please contact 
  207. Ron Schuster [76666,2322] via EasyPlex on CompuServe.
  208.  
  209. Contributors:
  210. Kim Kokkonen [76004,2611]
  211. Per Larsen [75470,1320]
  212. Ron Schuster [76666,2322]
  213. Roy Furman [72346,72]
  214.  
  215. 01/04/90  Version 4
  216.